Create a figure and a set of subplots.
This utility wrapper makes it convenient to create common layouts of subplots, including the enclosing figure object, in a single call.
Number of rows/columns of the subplot grid.
Controls sharing of properties among x (sharex) or y (sharey) axes:
When subplots have a shared x-axis along a column, only the x tick labels of the bottom subplot are created. Similarly, when subplots have a shared y-axis along a row, only the y tick labels of the first column subplot are created. To later turn other subplots' ticklabels on, use tick_params.
When subplots have a shared axis that has units, calling Axis.set_units will update each axis with the new units.
Note that it is not possible to unshare axes.
If True, extra dimensions are squeezed out from the returned array of Axes:
Defines the relative widths of the columns. Each column gets a relative width of width_ratios[i] / sum(width_ratios). If not given, all columns will have the same width. Equivalent to gridspec_kw={'width_ratios': [...]}.
Defines the relative heights of the rows. Each row gets a relative height of height_ratios[i] / sum(height_ratios). If not given, all rows will have the same height. Convenience for gridspec_kw={'height_ratios': [...]}.
Dict with keywords passed to the add_subplot call used to create each subplot.
Dict with keywords passed to the GridSpec constructor used to create the grid the subplots are placed on.
All additional keyword arguments are passed to the pyplot.figure call.
Figure
Axes or array of Axes
ax can be either a single Axes object, or an array of Axes objects if more than one subplot was created. The dimensions of the resulting array can be controlled with the squeeze keyword, see above.
Typical idioms for handling the return value are:
# using the variable ax for single a Axes fig, ax = plt.subplots() # using the variable axs for multiple Axes fig, axs = plt.subplots(2, 2) # using tuple unpacking for multiple Axes fig, (ax1, ax2) = plt.subplots(1, 2) fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(2, 2)
The names ax and pluralized axs are preferred over axes because for the latter it's not clear if it refers to a single Axes instance or a collection of these.
# First create some toy data:
x = np.linspace(0, 2*np.pi, 400)
y = np.sin(x**2)
# Create just a figure and only one subplot
fig, ax = plt.subplots()
ax.plot(x, y)
ax.set_title('Simple plot')
# Create two subplots and unpack the output array immediately
f, (ax1, ax2) = plt.subplots(1, 2, sharey=True)
ax1.plot(x, y)
ax1.set_title('Sharing Y axis')
ax2.scatter(x, y)
# Create four polar Axes and access them through the returned array
fig, axs = plt.subplots(2, 2, subplot_kw=dict(projection="polar"))
axs[0, 0].plot(x, y)
axs[1, 1].scatter(x, y)
# Share a X axis with each column of subplots
plt.subplots(2, 2, sharex='col')
# Share a Y axis with each row of subplots
plt.subplots(2, 2, sharey='row')
# Share both X and Y axes with all subplots
plt.subplots(2, 2, sharex='all', sharey='all')
# Note that this is the same as
plt.subplots(2, 2, sharex=True, sharey=True)
# Create figure number 10 with a single subplot
# and clears it if it already exists.
fig, ax = plt.subplots(num=10, clear=True)
matplotlib.pyplot.subplots
Shade regions defined by a logical mask using fill_between
Controlling view limits using margins and sticky_edges
Combining two subplots using subplots and GridSpec
Plot a confidence ellipse of a two-dimensional dataset
Creating boxes from error bars using PatchCollection
Demo of the histogram function's different histtype settings
The histogram (hist) function with multiple data sets
Line, Poly and RegularPoly Collection with autoscaling
Controlling the position and size of colorbars with Inset Axes
Building histograms using Rectangles and PolyCollections
Select indices from a collection using polygon selector
© 2012–2023 Matplotlib Development Team. All rights reserved.
Licensed under the Matplotlib License Agreement.
https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.subplots.html